home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / psion / devices < prev    next >
Text File  |  1995-03-31  |  27KB  |  740 lines

  1. PSIONICS FILE - DEVICES
  2. =======================
  3. Device driver interfaces
  4. Last modified 1994-09-13
  5. ========================
  6.  
  7. This document describes all known functions for all known device drivers. It
  8. does not include file IO, even when done through the same interfaces.
  9.  
  10. The device drivers documented are:
  11.   SND: Sound device
  12.   TIM: Timer device
  13.   ALM: Alarm device
  14.   WLD: World device
  15.   TTY: Serial port device
  16.   PAR: Parallel port device
  17.   FRC: Free running counter
  18.   XMD: XModem driver
  19.   YMD: YModem driver
  20.   Console device
  21.  
  22.  
  23. Types of device driver
  24. ----------------------
  25. On the Series 3, much functionality, including the filing system, is provided
  26. via device drivers. There are three kinds of device drivers:
  27. * physical device drivers: these drive the hardware directly
  28. * base logical device drivers: these provide a basic abstraction for working
  29.   with logical device drivers
  30. * stacked logical device drivers: these provide higher levels of abstraction
  31. Only logical device drivers need to know about physical device drivers; all
  32. user applications operate through logical device drivers.
  33.  
  34. For example, the 3-Link pod and cable might be accessed through a physical
  35. device driver called TTY.LNK: (all physical device drivers have a two part
  36. name). This is automatically loaded the first time that the logical device
  37. driver TTY: is opened, and TTY: will use it to actually communicate with the
  38. pod.
  39.  
  40. When TTY: is opened, the kernel will return a handle. Read and write operations
  41. on that handle will send data directly to and from the port. Alternatively,
  42. the XMD: device driver could be stacked on top of TTY: on that handle. Once
  43. this has been done, read and write on that handle will now be done via the XMD:
  44. driver, which wraps the data in the XModem protocol and calls the TTY: driver
  45. to do the actual output. There is no limit to how many device drivers can be
  46. stacked upon one another.
  47.  
  48.  
  49. Opening a handle
  50. ----------------
  51. A base logical device driver is opened with the IOOPEN keyword or the IoOpen
  52. system call; a stacked logical device driver is opened with IoOpen. The name is
  53. examined to see whether it has a colon as the fourth character but not the
  54. fifth; if so, it is split into a device name and a channel name. The kernel
  55. then checks that the logical device exists; if not, or if the name does not
  56. have the correct form, it prefixes "FIL:" to the name and tries again (FIL
  57. is the filing system logical device driver). For example:
  58.     "SND:"        device "SND"  channel name ""
  59.     "TTY:A"       device "TTY"  channel name "A"
  60.     "FIL:A:XXX"   device "FIL"  channel name "A:XXX"
  61.     "HELLO.TXT"   device "FIL"  channel name "HELLO.TXT"
  62.     "ROM::XXX"    device "FIL"  channel name "ROM::XXX"
  63.     "FIL:TTY:"    device "FIL"  channel name "TTY:"
  64.     "QXV:"        device "FIL"  channel name "QXV:"
  65. [the last example assumes there is no QXV device driver].
  66.  
  67. The filing system and the FIL: driver are described in the Psionics file
  68. FILEIO. All other known drivers are described here.
  69.  
  70. IOOPEN and IoOpen are passed a mode to open the device or file. Drivers other
  71. than the filing system and those specifically mentioning it ignore the mode.
  72. It is recommended that a mode of -1 be used, as this is always rejected by the
  73. filing system; thus an error in the device name or a missing driver will be
  74. detected.
  75.  
  76. A driver may refuse to open a given channel name, or all channels, more than
  77. a certain number of times without closing some first. For example, a TTY
  78. driver might only allow one open handle at a time for each port.
  79.  
  80.  
  81. Using the device driver
  82. -----------------------
  83. Once a device driver has been opened, it is accessed with the keywords IOW,
  84. IOA, and IOC (Series 3a only). These keywords offer the same services, and
  85. differ only in the way completion is indicated.
  86.  
  87. IOW waits until the operation completes, and then returns. No signal is
  88.     generated.
  89. IOA has an extra status variable argument. The variable is set to -46 at the
  90.     start of the operation, and then to the final result when it completes; a
  91.     signal is generated at this moment (it can be collected with IOWAIT or
  92.     IOWAITSTAT). Note that some operations complete immediately, and so the
  93.     status of -46 is never seen.
  94. IOC is like IOA, but if the operation completes immediately, it places the
  95.     result into the status variable and generates a signal. Thus the code
  96.     making the call can check the result in one place (after collecting the
  97.     signal) rather than two (after the call and after the signal).
  98.  
  99. Each call is passed a function number and two parameters for passing other
  100. information. The latter identify blocks of memory; the actual argument can be
  101. either the name of an OPL variable (typically the first element of an array),
  102. in which case that variable marks the start of the block, or it can be the #
  103. operator applied to the address of the block. The former is equivalent to
  104. #ADDR(variable).
  105.  
  106. If the parameter is shown as "unused", then any variable or value can be used,
  107. as it will be ignored; it is often convenient to use #0 as such an argument.
  108.  
  109. Unless stated otherwise, a successful call returns zero, and an unsuccessful
  110. call some non-zero error code.
  111.  
  112.  
  113. Standard functions
  114. ------------------
  115.  
  116. These functions apply to all drivers.
  117.  
  118. Function:   1 (read)
  119. Function:   2 (write)
  120. Argument 1: buffer
  121. Argument 2: count (word)
  122.  
  123. These functions are equivalent to the IOREAD and IOWRITE keywords. They read
  124. or write up to the specified number of bytes from or to the device; in the
  125. case of function 1, the count is changed to the actual amount read.
  126.  
  127. These functions can be used with any handle that is using a driver labelled
  128. as a data driver (such as the serial port device or the XModem driver).
  129.  
  130.  
  131. Function:   3
  132. Argument 1: unused
  133. Argument 2: unused
  134.  
  135. This will close the handle; it is equivalent to the IOCLOSE keyword.
  136.  
  137.  
  138. Function:   4
  139. Argument 1: unused
  140. Argument 2: unused
  141.  
  142. This will cancel any uncompleted function on the handle; the function will
  143. complete immediately, with the status variable set to -48 ("I/O cancelled").
  144. A signal will still be generated, and must be collected with IOWAITSTAT or
  145. IOWAIT.
  146.  
  147.  
  148. Sound device
  149. ------------
  150.  
  151. The sound device has the name "SND:". There are no channel names.
  152.  
  153.  
  154. Function:   1 (sound channel 1)
  155. Function:   2 (sound channel 2)
  156. Argument 1: note information
  157. Argument 2: word holding number of notes
  158. This function is supported by the HC, MC, and Series 3a only.
  159.  
  160. This plays a sequence of notes on the specified sound channel. The note
  161. information is an array of words, two per note; the first is the frequency of
  162. the note (in Hz), and the second the duration in beats (see function 7).
  163. The sound will not start until both these functions have been called (thus
  164. ensuring the sound is synchronized on both channels). The function completes
  165. when the specified channel finishes playing, even if the other has not.
  166.  
  167.  
  168. Function:   7
  169. Argument 1: 2 byte information block
  170. Argument 2: unused
  171.  
  172. The characteristics of the sound system are set according to the block:
  173.   Offset  0 (byte): beats per minute (2 to 240, default 120)
  174.   Offset  1 (byte): volume (0 max to 5 min)
  175. The beats per minute is only supported by the HC, MC, and Series 3a. On the
  176. Series 3a, volumes 1 and 2 are identical, as are 4 and 5. On the Series 3s,
  177. volumes 0 and 5 are unavailable.
  178.  
  179.  
  180. Function:   8
  181. Argument 1: 2 byte information block
  182. Argument 2: unused
  183.  
  184. The block is filled in with information about the sound channel, using the
  185. same format as function 7.
  186.  
  187.  
  188. Function:   9
  189. Argument 1: alarm type (0 = rings, 1 = chimes)
  190. Argument 2: unused
  191.  
  192. The specified alarm is played; this function completes when the sound has
  193. completely played.
  194.  
  195.  
  196. Function:   10
  197. Argument 1: phone number (cstr)
  198. Argument 2: parameter block
  199.  
  200. This generates DTMF dialling sounds. The number contains the digits to be
  201. dialled (0 to 9, *, #, and A to F can be used; E is the same as *, and F the
  202. same as #). The parameter block has the format:
  203.   Offset 0 (byte): tone length   )
  204.   Offset 1 (byte): delay length  ) all in 1/32 seconds
  205.   Offset 2 (word): pause length  )
  206.  
  207.  
  208.  
  209. Timer device
  210. ------------
  211.  
  212. The timer device has the name "TIM:". There are no channel names.
  213.  
  214. Function:   1
  215. Argument 1: delay in 1/10 seconds (long)
  216. Argument 2: unused
  217.  
  218. This will complete after the specified delay. Time when the machine is switched
  219. off is not counted as part of the delay. Changing the system clock will not
  220. affect the completion of this function.
  221.  
  222.  
  223. Function:   2
  224. Argument 1: abstime (long)
  225. Argument 2: unused
  226.  
  227. This will complete at the specified time. If the machine is switched off at
  228. that time, it will switch back on. Changing the system clock will affect the
  229. completion of this function.
  230.  
  231.  
  232. Alarm device
  233. ------------
  234.  
  235. The alarm device has the name "ALM:". There are no channel names.
  236.  
  237. Function:   1 (display date only)
  238. Function:   2 (display date and time)
  239. Argument 1: time specification block
  240. Argument 2: message (cstr)
  241.  
  242. This schedules an alarm, which causes a message box to be shown at some later
  243. time. The time specification block has the format:
  244.   Offset  0 (long): abstime when the alarm should sound
  245.   Offset  4 (long): abstime to be displayed in the message box
  246. The message (maximum 64 characters) is shown in the message box.
  247.  
  248. The function completes when the alarm goes off. If the machine is switched off
  249. at that time, it will switch back on. Changing the system clock will affect the
  250. completion of this function.
  251.  
  252.  
  253. Function:   10 (display date only)
  254. Function:   11 (display date and time)
  255. Argument 1: time specification block
  256. Argument 2: message (cstr)
  257. These functions are supported by the Series 3a only.
  258.  
  259. This schedules an alarm, which causes a message box to be shown at some later
  260. time. The time specification block has the format:
  261.   Offset  0 (long): abstime when the alarm should sound
  262.   Offset  4 (long): abstime to be displayed in the message box
  263.   Offset  8 (byte): length of name (L)
  264.   Offset  9 to L+8: name of alarm sound
  265.  
  266. These functions are identical to functions 1 and 2, except that the alarm sound
  267. is specified by the call. The sound name may be one of the following:
  268. - the name of a sound file; this is searched for in each of:
  269.     A:\WVE\name.WVE
  270.     B:\WVE\name.WVE
  271.     M:\WVE\name.WVE
  272.     ROM::name.WVE
  273.   [This appears to be the search order, but it is not documented.]
  274.   The Series 3a ROM contains the sounds:
  275.     SYS$AL01   Fanfare
  276.     SYS$AL02   Soft bells
  277.     SYS$AL03   Church bell
  278. - a single byte (thus offset 8 is set to 1) with the value 1 (for rings),
  279.   2 (for chimes), or 16 (for silence).
  280.  
  281.  
  282. World device
  283. ------------
  284.  
  285. The world device has the name "WLD:". There are no channel names.
  286.  
  287. This device gives access to the World database. This includes the built-in
  288. database and any one world file. If the World application is running, this is
  289. the file it currently has open. Otherwise it is the last world file to be open.
  290. Several functions use a "city name block". This is a 42 byte block with the
  291. format:
  292.   Offset  0 to 20: name of a city (cstr)
  293.   Offset 21 to 41: name of a country (cstr)
  294. Unless stated otherwise, the country is that in which the city lies.
  295.  
  296. Many functions establish or use a searching order. This can be set to:
  297. - all cities, in alphabetical order ("city order")
  298. - capital cities, in alphabetical order of country ("country order")
  299. - unspecifed ("random order")
  300. Search order is cyclic: the last city or country is followed by the first.
  301.  
  302.  
  303. Function:   10
  304. Argument 1: clue (cstr)
  305. Argument 2: city name block
  306.  
  307. This locates a city whose name begins with the clue (the search is not case
  308. sensitive, so "lon" will find London, but "ond" will not). If successful, the
  309. city block is filled in with the city, and city order is set.
  310.  
  311.  
  312. Function:   11
  313. Argument 1: clue (cstr)
  314. Argument 2: city name block
  315.  
  316. This locates a country whose name begins with the clue (the search is not case
  317. sensitive, so "lon" will find London, but "ond" will not). If successful, the
  318. city block is filled in with the capital city of the country, and country order
  319. is set.
  320.  
  321.  
  322. Function:   12
  323. Argument 1: city name (cstr)
  324. Argument 2: unused
  325.  
  326. This function succeeds if the city name (ignoring case) is the same as the last
  327. city returned by functions 10, 13, 14, or 15. Random order is set.
  328. @Why ?@
  329.  
  330.  
  331. Function:   13 (next city)
  332. Function:   14 (previous city)
  333. Argument 1: city name block
  334. Argument 2: unused
  335.  
  336. These functions fill the block with the next (or previous) city in the current
  337. search order.
  338.  
  339.  
  340. Function:   15
  341. Argument 1: city name block
  342. Argument 2: unused
  343.  
  344. This function fills the block with the home city; city order is set.
  345.  
  346.  
  347. Function:   16
  348. Argument 1: unused
  349. Argument 2: unused
  350.  
  351. This function sets the home city to the last city returned.
  352.  
  353.  
  354. Function:   17
  355. Argument 1: city name block
  356. Argument 2: unused
  357.  
  358. This function fills the block with the capital city of the default country;
  359. country order is set.
  360.  
  361.  
  362. Function:   18
  363. Argument 1: unused
  364. Argument 2: unused
  365.  
  366. This function sets the default country to that of the last city returned.
  367.  
  368.  
  369.   IOW ("WLD:", 19, original, dial_25)
  370. Function:   19
  371. Argument 1: original number (cstr)
  372. Argument 2: diallable number (cstr)
  373.  
  374. This function generates a diallable number (up to 24 characters) from the
  375. original number, using the following rules:
  376. - all characters before the first digit are stripped from the number;
  377. - the number then ends at the first character other than a digit, space, or the
  378.   special characters * # , and - (star, hash, comma, and dash);
  379. - if there are any spaces or dashes in the number, they are removed and the
  380.   diallable number is modified as follows:
  381.   * if the first digit was a zero, it is removed;
  382.   * if the home city is not in the default country, the sequence is prefixed
  383.     with the international sequence to dial from the home city to the default
  384.     country;
  385. - if not, the number is precisely those characters left.
  386.  
  387. For example, "abc,123,456xx789" generates "123,456". Assuming that the default
  388. country is the UK and the default city is in the USA, "abc00-34 56x78"
  389. generates "01144003456".
  390.  
  391.  
  392. Function:   22
  393. Argument 1: 80 byte buffer
  394. Argument 2: unused
  395.  
  396. This function fills the buffer with information about the last city returned:
  397.   Offset  0 to  20: (cstr) city name
  398.   Offset 21 to  41: (cstr) country name
  399.   Offset 42 (byte): country time code (see below)
  400.   Offset 43 (byte): DST rule: 0 = none, 2 = European, 4 = North, 8 = South
  401.   Offset 44 (word): minutes ahead of GMT for city
  402.   Offset 46 (word): city latitude in minutes north (negative means south)
  403.   Offset 48 (word): city longtitude in minutes west (negative means east)
  404.   Offset 50 to  66: (cstr) dial code from home city
  405.   Offset 67 to  75: (cstr) area code of city
  406.   Offset 76 (word): X coordinate of city on map (in pixels)
  407.   Offset 78 (word): Y coordinate of city on map (in pixels)
  408.  
  409. The country time code gives the "central" time in the country. It is an offset
  410. from GMT in units of 30 minutes; for countries behind GMT, 256 is added (or
  411. equivalently, the byte is signed). In practice, this is the time for the
  412. capital city, with the three exceptions of Australia (code 19), Canada, and
  413. the USA (both code $F2 or -14). @Why ?@
  414.  
  415.  
  416. Function:   23
  417. Argument 1: 66 byte buffer
  418. Argument 2: unused
  419.  
  420. This function fills the buffer with information about the country of the last
  421. city returned:
  422.   Offset  0 to  20: (cstr) city name
  423.   Offset 21 to  41: (cstr) country name
  424.   Offset 42 (byte): country time code (see above)
  425.   Offset 43 (byte): DST rule: 0 = none, 2 = European, 4 = North, 8 = South
  426.   Offset 44 (word): minutes ahead of GMT for capital city
  427.   Offset 46 to  50: (cstr) national dialling code
  428.   Offset 51 to  55: (cstr) international dialling code
  429.   Offset 56 to  60: (cstr) country code
  430.  
  431.  
  432. Function:   25
  433. Argument 1: city name block
  434. Argument 2: unused
  435.  
  436. This function returns the next city in the same country as the last city
  437. returned (using city order).
  438.  
  439.  
  440. Serial port device (data device)
  441. --------------------------------
  442.  
  443. The serial port device has the name "TTY:". The channel name is a single
  444. letter from A to Z, identifying the particular port to use. Which ports are
  445. actually provided depends on the specific system.
  446.  
  447. An open serial port can be read and written with IOREAD and IOWRITE, or with
  448. IOW functions 1 and 2.
  449.  
  450.  
  451. Function:   7
  452. Argument 1: 12 byte control block
  453. Argument 2: unused
  454.  
  455. This function sets various characteristics of the serial port. The control
  456. block has the format:
  457.   Offset  0 (byte): transmit baud rate
  458.   Offset  1 (byte): receive baud rate
  459.     Baud rates are encoded as:
  460.      1 =    50      7 =   600     13 =  4800     19 = 115000
  461.      2 =    75      8 =  1200     14 =  7200
  462.      3 =   110      9 =  1800     15 =  9600
  463.      4 =   134     10 =  2000     16 = 19200
  464.      5 =   150     11 =  2400     17 = 38400
  465.      6 =   300     12 =  3600     18 = 56000
  466.   Offset  2 (byte): framing
  467.     Bits 0 to 3: number of data bits minus 5 (e.g. 3 means 8 bits)
  468.     Bit 4:       clear for 1 stop bit, set for 2 stop bits
  469.     Bit 5:       parity bit enabled if set
  470.   Offset  3 (byte): 0 = no parity, 1 = even parity, 2 = odd parity
  471.   Offset  4 (byte): handshaking
  472.     Bits 0 to 1: 3 = XON handshaking, 0 = no XON handshaking
  473.     Bit 2:       0 = RTS handshaking, 1 = no RTS handshaking
  474.     Bit 3:       1 = DSR handshaking, 0 = no DSR handshaking
  475.     (Any combination of XON, RTS, and DSR can be set at once.)
  476.   Offset  5 (byte): XON character (usually 17)
  477.   Offset  6 (byte): XOFF character (usually 19)
  478.   Offset  7 (byte): flags
  479.     Bit 0: ignore parity errors
  480.   Offset  8 (long): terminating mask
  481. The terminating mask specifies which of the characters with codes 0 to 31
  482. terminate a read. For example, if bits 10 and 13 are set, then a read on the
  483. port will terminate after reading a byte with value 10 or 13.
  484.  
  485.  
  486. Function:   8
  487. Argument 1: 12 byte control block
  488. Argument 2: unused
  489.  
  490. This function fills the control block with the current settings (see function
  491. 7).
  492.  
  493.  
  494. Function:   9
  495. Argument 1: unused
  496. Argument 2: unused
  497.  
  498. This function discards any buffered input and any error state. Any handshaking
  499. is set to restart reception.
  500.  
  501.  
  502. Function:   10
  503. Argument 1: count (word)
  504. Argument 2: unused
  505.  
  506. The count is set to the number of bytes buffered and waiting to be read.
  507.  
  508.  
  509. Function:   11
  510. Argument 1: 2 byte control block
  511. Argument 2: unused
  512.  
  513. The first byte of the control block is set to indicate the state of the modem
  514. control lines:
  515.     Bit 0: set if CTS active
  516.     Bit 1: set if DSR active
  517.     Bit 2: set if DCD active
  518.  
  519. The second byte specifies the new setting for the DTR line:
  520.     0 = leave unchanged
  521.     1 = set DTR active
  522.     2 = set DTR inactive
  523.  
  524.  
  525. Function:   12
  526. Argument 1: 6 byte information block
  527. Argument 2: unused
  528.  
  529. The information block is filled in to indicate which facilites are supported
  530. by the port.
  531.   Offset  0 (long):
  532.     Bit  0: set if supports 50 baud
  533.     Bit  1: set if supports 75 baud
  534.     Bit  2: set if supports 110 baud
  535.     Bit  3: set if supports 134 baud
  536.     Bit  4: set if supports 150 baud
  537.     Bit  5: set if supports 300 baud
  538.     Bit  6: set if supports 600 baud
  539.     Bit  7: set if supports 1200 baud
  540.     Bit  8: set if supports 1800 baud
  541.     Bit  9: set if supports 2000 baud
  542.     Bit 10: set if supports 2400 baud
  543.     Bit 11: set if supports 3600 baud
  544.     Bit 12: set if supports 4800 baud
  545.     Bit 13: set if supports 7200 baud
  546.     Bit 14: set if supports 9600 baud
  547.     Bit 15: set if supports 19200 baud
  548.     Bit 16: set if supports 38400 baud
  549.     Bit 17: set if supports 56000 baud
  550.   Offset  4 (word):
  551.     Bit  0: set if supports 5 bits
  552.     Bit  1: set if supports 6 bits
  553.     Bit  2: set if supports 7 bits
  554.     Bit  3: set if supports 8 bits
  555.     Bit  4: set if supports 2 stop bits
  556.     Bit  5: set if supports even parity
  557.     Bit  6: set if supports odd parity
  558.     Bit  7: set if supports mark parity
  559.     Bit  8: set if supports space parity
  560.     Bit  9: set if supports setting DTR
  561.     Bit 10: set if supports different transmit and receive baud rates
  562.     Bit 11: set if supports soft xon/xoff characters
  563.  
  564.  
  565. Parallel port device (data device)
  566. ----------------------------------
  567.  
  568. The parallel port device has the name "PAR:". The channel name is a single
  569. letter from A to Z, identifying the particular port to use. Which ports are
  570. actually provided depends on the specific system. A port will consume power
  571. while open.
  572.  
  573. An open parallel port can be written with IOWRITE, or with IOW function 2.
  574.  
  575. No other functions are available on the Series 3.
  576.  
  577.  
  578. Free running counter
  579. --------------------
  580.  
  581. The Free running counter has the name "FRC:". There are no channel names. It
  582. is only available on the Series 3a. Only one process may have the FRC open
  583. at a time, and so it should be closed as soon as possible.
  584.  
  585. In the following description, an "FRC-tick" is 1/1024 seconds.
  586.  
  587.  
  588. Function:   1
  589. Argument 1: (word) set to current count
  590. Argument 2: unused
  591.  
  592. The current setting of the counter is placed in the word. If the counter is
  593. in mode 1, the count is then reset to zero (the counter continues counting).
  594. This call will not complete while the counter is zero.
  595.  
  596.  
  597. Function:   15
  598. Argument 1: (word) operating mode (0 or 1)
  599. Argument 2: (word) step time (10 to 65535)
  600.  
  601. Starts the counter from zero. Mode 0 means that the counter will increment
  602. every FRC-tick. Mode 1 means that the counter will increment at every N
  603. FRC-ticks, where N is the step time. Any uncompleted function on the counter
  604. will be completed.
  605.  
  606.  
  607. XModem and YModem drivers (data device)
  608. ---------------------------------------
  609.  
  610. The XModem driver has the name "XMD:", and the YModem driver the name "YMD:".
  611. There are no channel names. Both are stacked on to another data device.
  612.  
  613. Once stacked, the driver will use the underlying device to transfer data
  614. using the XModem (single transfer) or YModem (multiple transfer) protocol.
  615. These protocols have a number of variants:
  616. - XModem may use checksums or CRCs on each frame. CRCs are more reliable.
  617. - YModem may use the error correcting or G mode. The G mode does not allow
  618.   errors to be corrected, only detected.
  619. - The transfer may use short frames (128 data bytes) only, or both short and
  620.   long frames (1024 data bytes).
  621.  
  622. Function 1 is used to receive data. The initial value of the length argument
  623. will be ignored, and a whole frame (128 or 1024) bytes will be placed in the
  624. buffer, which must therefore be large enough. When an end-of-file message is
  625. received, the function will fail with error -36.
  626.  
  627. Function 2 is used to send data. The length is used as follows:
  628.        0 : an end-of-file message is sent
  629.      128: a short frame is sent
  630.     1024: a long frame is sent
  631. If the length is any other value, the specified amount of data is transferred,
  632. followed by enough $1A bytes to fill a frame (a short frame if the length is
  633. less than 128, and a long frame otherwise).
  634.  
  635. With YModem, the first frame must be a short frame with the following contents,
  636. in order:
  637.   - (cstr) file name
  638.   - file length in bytes (decimal digits)
  639.   - a single space, then the abstime file last modified (octal digits)
  640.   - a single space, then the file mode, using Unix conventions (octal digits)
  641.   - a single space, then the sending software version number (octal digits)
  642. The last field or fields may be omitted, provided that the name is present.
  643. The rest of the frame must contain only zero bytes. A frame consisting only of
  644. 128 zero bytes indicates that there are no more files.
  645.  
  646.  
  647. Function:   10
  648. Argument 1: (word) direction: 0 = transmit, 1 = receive
  649. Argument 2: (word) mode
  650.  
  651. This establishes a connection with the other end of the link. The direction
  652. indicates which way the file transfer will take place. The mode is one of
  653. the following values:
  654.   If long frames are to be rejected while receiving:
  655.     XModem:
  656.       0 = CRC mode if supported by far end, otherwise checksum mode
  657.       1 = CRC mode
  658.       2 = Checksum mode
  659.     YModem:
  660.       3 = Error correcting mode
  661.       4 = G mode
  662.   If long frames are to be accepted while receiving:
  663.     XModem:
  664.       $8001 = CRC mode
  665.     YModem:
  666.       $8003 = Error correcting mode
  667.       $8004 = G mode
  668.  
  669. With YModem, this function must be called for each file.
  670.  
  671.  
  672. Function:   11
  673. Argument 1: unused
  674. Argument 2: unused
  675.  
  676. This disconnects an existing connection while leaving the driver attached.
  677. With YModem, this function should not be called between files.
  678.  
  679.  
  680. Console device
  681. --------------
  682.  
  683. This is a special device that does not need to be opened; it has the handle -2.
  684.  
  685.  
  686. Function:   7
  687. Argument 1: (word) the value 0
  688. Argument 2: (word) style: 0 = normal, 2 = inverse, 4 = underlined, 6 = both
  689.  
  690. This alters the text style as specified.
  691.  
  692.  
  693. Function:   7
  694. Argument 1: (word) the value 2
  695. Argument 2: rectangle
  696.  
  697. This clears an area described by the rectangle:
  698.   Offset  0 (word): left   coordinate (included)
  699.   Offset  2 (word): top    coordinate (included)
  700.   Offset  4 (word): right  coordinate (excluded)
  701.   Offset  7 (word): bottom coordinate (excluded)
  702.  
  703.  
  704. Function:   7
  705. Argument 1: (word) the value 17
  706. Argument 2: control block
  707.  
  708. This sets the font type for the text window, and (as a side effect) resizes
  709. and moves the current screen (as set by the SCREEN keyword). The control word
  710. has the format:
  711.   Offset  0 (word): font ID plus $3FFF
  712.   Offset  2 (word): style: 0 = normal, 1 = bold, 2 = double size
  713.  
  714.  
  715.   IOW (-2, 8, args%(), args%())
  716. Function:   8
  717. Argument 1: information block
  718. Argument 2: must be the same as argument 1
  719.  
  720. This function places the cursor position, relative to the specified rectangle,
  721. in the information block. This has the format:
  722.   Offset  0 (word): left   limit
  723.   Offset  2 (word): top    limit
  724.   Offset  4 (word): right  limit @why ?@
  725.   Offset  6 (word): bottom limit @why ?@
  726.   Offset  8 (word): set to cursor x coordinate
  727.   Offset 10 (word): set to cursor y coordinate
  728. All coordinates are in character positions, as used by the SCREEN keyword.
  729.  
  730.  
  731. Function:   14
  732. Argument 1: array of two words
  733. Argument 2: unused
  734.  
  735. This function is equivalent to the GETEVENT keyword. The TESTEVENT keyword
  736. also uses this function, testing to see if the status is -46 or not. This
  737. function can be called from OPL programs that are not OPA applications.
  738.  
  739. @Lots more still in the manual@
  740.